home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / lang / Object.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  22.6 KB  |  474 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Object.java    1.47 98/10/01
  3.  *
  4.  * Copyright 1994-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.lang;
  16.  
  17. /**
  18.  * Class <code>Object</code> is the root of the class hierarchy. 
  19.  * Every class has <code>Object</code> as a superclass. All objects, 
  20.  * including arrays, implement the methods of this class. 
  21.  *
  22.  * @author  unascribed
  23.  * @version 1.47, 10/01/98
  24.  * @see     java.lang.Class
  25.  * @since   JDK1.0
  26.  */
  27. public class Object {
  28.  
  29.     private static native void registerNatives();
  30.     static {
  31.         registerNatives();
  32.     }
  33.  
  34.     /**
  35.      * Returns the runtime class of an object. That <tt>Class</tt> 
  36.      * object is the object that is locked by <tt>static synchronized</tt> 
  37.      * methods of the represented class.
  38.      *
  39.      * @return  the object of type <code>Class</code> that represents the
  40.      *          runtime class of the object.
  41.      */
  42.     public final native Class getClass();
  43.  
  44.     /**
  45.      * Returns a hash code value for the object. This method is 
  46.      * supported for the benefit of hashtables such as those provided by 
  47.      * <code>java.util.Hashtable</code>. 
  48.      * <p>
  49.      * The general contract of <code>hashCode</code> is: 
  50.      * <ul>
  51.      * <li>Whenever it is invoked on the same object more than once during 
  52.      *     an execution of a Java application, the <tt>hashCode</tt> method 
  53.      *     must consistently return the same integer, provided no information 
  54.      *     used in <tt>equals</tt> comparisons on the object is modified.
  55.      *     This integer need not remain consistent from one execution of an
  56.      *     application to another execution of the same application. 
  57.      * <li>If two objects are equal according to the <tt>equals(Object)</tt>
  58.      *     method, then calling the <code>hashCode</code> method on each of 
  59.      *     the two objects must produce the same integer result. 
  60.      * <li>It is <em>not</em> required that if two objects are unequal 
  61.      *     according to the {@link java.lang.Object#equals(java.lang.Object)} 
  62.      *     method, then calling the <tt>hashCode</tt> method on each of the 
  63.      *     two objects must produce distinct integer results.  However, the 
  64.      *     programmer should be aware that producing distinct integer results 
  65.      *     for unequal objects may improve the performance of hashtables.
  66.      * </ul>
  67.      * <p>
  68.      * As much as is reasonably practical, the hashCode method defined by 
  69.      * class <tt>Object</tt> does return distinct integers for distinct 
  70.      * objects. (This is typically implemented by converting the internal 
  71.      * address of the object into an integer, but this implementation 
  72.      * technique is not required by the 
  73.      * Java<font size="-2"><sup>TM</sup></font> programming language.)
  74.      *
  75.      * @return  a hash code value for this object.
  76.      * @see     java.lang.Object#equals(java.lang.Object)
  77.      * @see     java.util.Hashtable
  78.      */
  79.     public native int hashCode();
  80.  
  81.     /**
  82.      * Indicates whether some other object is "equal to" this one.
  83.      * <p>
  84.      * The <code>equals</code> method implements an equivalence relation: 
  85.      * <ul>
  86.      * <li>It is <i>reflexive</i>: for any reference value <code>x</code>, 
  87.      *     <code>x.equals(x)</code> should return <code>true</code>. 
  88.      * <li>It is <i>symmetric</i>: for any reference values <code>x</code> and 
  89.      *     <code>y</code>, <code>x.equals(y)</code> should return 
  90.      *     <code>true</code> if and only if <code>y.equals(x)</code> returns 
  91.      *     <code>true</code>. 
  92.      * <li>It is <i>transitive</i>: for any reference values <code>x</code>, 
  93.      *     <code>y</code>, and <code>z</code>, if <code>x.equals(y)</code>
  94.      *     returns  <code>true</code> and <code>y.equals(z)</code> returns 
  95.      *     <code>true</code>, then <code>x.equals(z)</code> should return 
  96.      *     <code>true</code>. 
  97.      * <li>It is <i>consistent</i>: for any reference values <code>x</code> 
  98.      *     and <code>y</code>, multiple invocations of <tt>x.equals(y)</tt>
  99.      *     consistently return <code>true</code> or consistently return 
  100.      *     <code>false</code>, provided no information used in
  101.      *     <code>equals</code> comparisons on the object is modified.
  102.      * <li>For any non-null reference value <code>x</code>, 
  103.      *     <code>x.equals(null)</code> should return <code>false</code>.
  104.      * </ul>
  105.      * <p>
  106.      * The <tt>equals</tt> method for class <code>Object</code> implements 
  107.      * the most discriminating possible equivalence relation on objects; 
  108.      * that is, for any reference values <code>x</code> and <code>y</code>, 
  109.      * this method returns <code>true</code> if and only if <code>x</code> and 
  110.      * <code>y</code> refer to the same object (<code>x==y</code> has the 
  111.      * value <code>true</code>). 
  112.      *
  113.      * @param   obj   the reference object with which to compare.
  114.      * @return  <code>true</code> if this object is the same as the obj
  115.      *          argument; <code>false</code> otherwise.
  116.      * @see     java.lang.Boolean#hashCode()
  117.      * @see     java.util.Hashtable
  118.      */
  119.     public boolean equals(Object obj) {
  120.     return (this == obj);
  121.     }
  122.  
  123.     /**
  124.      * Creates and returns a copy of this object.  The precise meaning 
  125.      * of "copy" may depend on the class of the object. The general 
  126.      * intent is that, for any object <tt>x</tt>, the expression:
  127.      * <blockquote>
  128.      * <pre>
  129.      * x.clone() != x</pre></blockquote>
  130.      * will be true, and that the expression:
  131.      * <blockquote>
  132.      * <pre>
  133.      * x.close.getClass() == x.getClass()</pre></blockquote>
  134.      * will be <tt>true</tt>, but these are not absolute requirements. 
  135.      * While it is typically the case that:
  136.      * <blockquote>
  137.      * <pre>
  138.      * x.close.equals(x)</pre></blockquote>
  139.      * will be <tt>true</tt>, this is not an absolute requirement. 
  140.      * Copying an object will typically entail creating a new instance of 
  141.      * its class, but it also may require copying of internal data 
  142.      * structures as well.  No constructors are called.
  143.      * <p>
  144.      * The method <tt>clone</tt> for class <tt>Object</tt> performs a 
  145.      * specific cloning operation. First, if the class of this object does 
  146.      * not implement the interface <tt>Cloneable</tt>, then a 
  147.      * <tt>CloneNotSupportedException</tt> is thrown. Note that all arrays 
  148.      * are considered to implement the interface <tt>Cloneable</tT>. 
  149.      * Otherwise, this method creates a new instance of the class of this 
  150.      * object and initializes all its fields with exactly the contents of 
  151.      * the corresponding fields of this object, as if by assignment; the
  152.      * contents of the fields are not themselves cloned. Thus, this method 
  153.      * performs a "shallow copy" of this object, not a "deep copy" operation.
  154.      * <p>
  155.      * The class <tt>Object</tt> does not itself implement the interface 
  156.      * <tt>Cloneable</tt>, so calling the <tt>clone</tt> method on an object 
  157.      * whose class is <tt>Object</tt> will result in throwing an
  158.      * exception at run time. The <tt>clone</tt> method is implemented by 
  159.      * the class <tt>Object</tt> as a convenient, general utility for 
  160.      * subclasses that implement the interface <tt>Cloneable</tt>, possibly 
  161.      * also overriding the <tt>clone</tt> method, in which case the
  162.      * overriding definition can refer to this utility definition by the 
  163.      * call:
  164.      * <blockquote>
  165.      * <pre>
  166.      * super.clone()</pre></blockquote>
  167.      *
  168.      * @return     a clone of this instance.
  169.      * @exception  CloneNotSupportedException  if the object's class does not
  170.      *               support the <code>Cloneable</code> interface. Subclasses
  171.      *               that override the <code>clone</code> method can also
  172.      *               throw this exception to indicate that an instance cannot
  173.      *               be cloned.
  174.      * @exception  OutOfMemoryError            if there is not enough memory.
  175.      * @see        java.lang.Cloneable
  176.      */
  177.     protected native Object clone() throws CloneNotSupportedException;
  178.  
  179.     /**
  180.      * Returns a string representation of the object. In general, the 
  181.      * <code>toString</code> method returns a string that 
  182.      * "textually represents" this object. The result should 
  183.      * be a concise but informative representation that is easy for a 
  184.      * person to read.
  185.      * It is recommendedthat all subclasses override this method.
  186.      * <p>
  187.      * The <code>toString</code> method for class <code>Object</code> 
  188.      * returns a string consisting of the name of the class of which the 
  189.      * object is an instance, the at-sign character `<code>@</code>', and 
  190.      * the unsigned hexadecimal representation of the hash code of the 
  191.      * object. In other words, this method returns a string equal to the 
  192.      * value of:
  193.      * <blockquote>
  194.      * <pre>
  195.      * getClass().getName() + '@' + Integer.toHexString(hashCode())
  196.      * </pre></blockquote>
  197.      *
  198.      * @return  a string representation of the object.
  199.      */
  200.     public String toString() {
  201.     return getClass().getName() + "@" + Integer.toHexString(hashCode());
  202.     }
  203.  
  204.     /**
  205.      * Wakes up a single thread that is waiting on this object's 
  206.      * monitor. If any threads are waiting on this object, one of them 
  207.      * is chosen to be awakened. The choice is arbitrary and occurs at 
  208.      * the discretion of the implementation. A thread waits on an object's 
  209.      * monitor by calling one of the <code>wait</code> methods.
  210.      * <p>
  211.      * The awakened thread will not be able to proceed until the current 
  212.      * thread relinquishes the lock on this object. The awakened thread will 
  213.      * compete in the usual manner with any other threads that might be 
  214.      * actively competing to synchronize on this object; for example, the 
  215.      * awakened thread enjoys no reliable privilege or disadvantage in being 
  216.      * the next thread to lock this object.
  217.      * <p>
  218.      * This method should only be called by a thread that is the owner 
  219.      * of this object's monitor. A thread becomes the owner of the 
  220.      * object's monitor in one of three ways: 
  221.      * <ul>
  222.      * <li>By executing a synchronized instance method of that object. 
  223.      * <li>By executing the body of a <code>synchronized</code> statement 
  224.      *     that synchronizes on the object. 
  225.      * <li>For objects of type <code>Class,</code> by executing a 
  226.      *     synchronized static method of that class. 
  227.      * </ul>
  228.      * <p>
  229.      * Only one thread at a time can own an object's monitor. 
  230.      *
  231.      * @exception  IllegalMonitorStateException  if the current thread is not
  232.      *               the owner of this object's monitor.
  233.      * @see        java.lang.Object#notifyAll()
  234.      * @see        java.lang.Object#wait()
  235.      */
  236.     public final native void notify();
  237.  
  238.     /**
  239.      * Wakes up all threads that are waiting on this object's monitor. A 
  240.      * thread waits on an object's monitor by calling one of the 
  241.      * <code>wait</code> methods.
  242.      * <p>
  243.      * The awakened threads will not be able to proceed until the current 
  244.      * thread relinquishes the lock on this object. The awakened threads 
  245.      * will compete in the usual manner with any other threads that might 
  246.      * be actively competing to synchronize on this object; for example, 
  247.      * the awakened threads enjoy no reliable privilege or disadvantage in 
  248.      * being the next thread to lock this object.
  249.      * <p>
  250.      * This method should only be called by a thread that is the owner 
  251.      * of this object's monitor. See the <code>notify</code> method for a 
  252.      * description of the ways in which a thread can become the owner of 
  253.      * a monitor. 
  254.      *
  255.      * @exception  IllegalMonitorStateException  if the current thread is not
  256.      *               the owner of this object's monitor.
  257.      * @see        java.lang.Object#notify()
  258.      * @see        java.lang.Object#wait()
  259.      */
  260.     public final native void notifyAll();
  261.  
  262.     /**
  263.      * Causes current thread to wait until either another thread invokes the 
  264.      * {@link java.lang.Object#notify()} method or the 
  265.      * {@link java.lang.Object#notifyAll()} method for this object, or a 
  266.      * specified amount of time has elapsed. 
  267.      * <p>
  268.      * The current thread must own this object's monitor. 
  269.      * <p>
  270.      * This method causes the current thread (call it <var>T</var>) to 
  271.      * place itself in the wait set for this object and then to relinquish 
  272.      * any and all synchronization claims on this object. Thread <var>T</var> 
  273.      * becomes disabled for thread scheduling purposes and lies dormant 
  274.      * until one of four things happens:
  275.      * <ul>
  276.      * <li>Some other thread invokes the <tt>notify</tt> method for this 
  277.      * object and thread <var>T</var> happens to be arbitrarily chosen as 
  278.      * the thread to be awakened. 
  279.      * <li>Some other thread invokes the <tt>notifyAll</tt> method for this 
  280.      * object. 
  281.      * <li>Some other thread {@link java.lang.Thread#interrupt() interrupts} 
  282.      * thread <var>T</var>. 
  283.      * The specified amount of real time has elapsed, more or less.  If 
  284.      * <tt>timeout</tt> is zero, however, then real time is not taken into 
  285.      * consideration and the thread simply waits until notified. 
  286.      * </ul>
  287.      * The thread <var>T</var> is then removed from the wait set for this 
  288.      * object and re-enabled for thread scheduling. It then competes in the 
  289.      * usual manner with other threads for the right to synchronize on the 
  290.      * object; once it has gained control of the object, all its 
  291.      * synchronization claims on the object are restored to the status quo 
  292.      * ante - that is, to the situation as of the time that the <tt>wait</tt> 
  293.      * method was invoked. Thread <var>T</var> then returns from the 
  294.      * invocation of the <tt>wait</tt> method. Thus, on return from the 
  295.      * <tt>wait</tt> method, the synchronization state of the object and of 
  296.      * thread <tt>T</tt> is exactly as it was when the <tt>wait</tt> method 
  297.      * was invoked. 
  298.      * <p>
  299.      * If the current thread is 
  300.      * {@link java.lang.Thread#interrupt() interrupted} by another thread 
  301.      * while it is waiting, then an <tt>InterruptedException</tt> is thrown. 
  302.      * This exception is not thrown until the lock status of this object has 
  303.      * been restored as described above.
  304.      * <p>
  305.      * Note that the <tt>wait</tt> method, as it places the current thread 
  306.      * into the wait set for this object, unlocks only this object; any 
  307.      * other objects on which the current thread may be synchronized remain 
  308.      * locked while the thread waits.
  309.      * <p>
  310.      * This method should only be called by a thread that is the owner 
  311.      * of this object's monitor. See the <code>notify</code> method for a 
  312.      * description of the ways in which a thread can become the owner of 
  313.      * a monitor. 
  314.      *
  315.      * @param      timeout   the maximum time to wait in milliseconds.
  316.      * @exception  IllegalArgumentException      if the value of timeout is
  317.      *             negative.
  318.      * @exception  IllegalMonitorStateException  if the current thread is not
  319.      *               the owner of the object's monitor.
  320.      * @exception  InterruptedException if another thread has interrupted
  321.      *             the current thread.  The <i>interrupted status</i> of the
  322.      *             current thread is cleared when this exception is thrown.
  323.      * @see        java.lang.Object#notify()
  324.      * @see        java.lang.Object#notifyAll()
  325.      */
  326.     public final native void wait(long timeout) throws InterruptedException;
  327.  
  328.     /**
  329.      * Causes current thread to wait until another thread invokes the 
  330.      * {@link java.lang.Object#notify()} method or the 
  331.      * {@link java.lang.Object#notifyAll()} method for this object, or 
  332.      * some other thread interrupts the current thread, or a certain 
  333.      * amount of real time has elapsed. 
  334.      * <p>
  335.      * This method is similar to the <code>wait</code> method of one 
  336.      * argument, but it allows finer control over the amount of time to 
  337.      * wait for a notification before giving up. The amount of real time, 
  338.      * measured in nanoseconds, is given by:
  339.      * <blockquote>
  340.      * <pre>
  341.      * 1000000*millis+nanos</pre></blockquote>
  342.      * <p>
  343.      * In all other respects, this method does the same thing as the 
  344.      * method {@link #wait(long)} of one argument. In particular, 
  345.      * <tt>wait(0, 0)</tt> means the same thing as <tt>wait(0)</tt>.
  346.      * <p>
  347.      * The current thread must own this object's monitor. The thread 
  348.      * releases ownership of this monitor and waits until either of the 
  349.      * following two conditions has occurred: 
  350.      * <ul>
  351.      * <li>Another thread notifies threads waiting on this object's monitor 
  352.      *     to wake up either through a call to the <code>notify</code> method 
  353.      *     or the <code>notifyAll</code> method. 
  354.      * <li>The timeout period, specified by <code>timeout</code> 
  355.      *     milliseconds plus <code>nanos</code> nanoseconds arguments, has 
  356.      *     elapsed. 
  357.      * </ul>
  358.      * <p>
  359.      * The thread then waits until it can re-obtain ownership of the 
  360.      * monitor and resumes execution 
  361.      * <p>
  362.      * This method should only be called by a thread that is the owner 
  363.      * of this object's monitor. See the <code>notify</code> method for a 
  364.      * description of the ways in which a thread can become the owner of 
  365.      * a monitor. 
  366.      *
  367.      * @param      timeout   the maximum time to wait in milliseconds.
  368.      * @param      nano      additional time, in nanoseconds range
  369.      *                       0-999999.
  370.      * @exception  IllegalArgumentException      if the value of timeout is
  371.      *                negative or the value of nanos is
  372.      *                not in the range 0-999999.
  373.      * @exception  IllegalMonitorStateException  if the current thread is not
  374.      *               the owner of this object's monitor.
  375.      * @exception  InterruptedException if another thread has interrupted
  376.      *             the current thread.  The <i>interrupted status</i> of the
  377.      *             current thread is cleared when this exception is thrown.
  378.      */
  379.     public final void wait(long timeout, int nanos) throws InterruptedException {
  380.         if (timeout < 0) {
  381.             throw new IllegalArgumentException("timeout value is negative");
  382.         }
  383.  
  384.         if (nanos < 0 || nanos > 999999) {
  385.             throw new IllegalArgumentException(
  386.                 "nanosecond timeout value out of range");
  387.         }
  388.  
  389.     if (nanos >= 500000 || (nanos != 0 && timeout == 0)) {
  390.         timeout++;
  391.     }
  392.  
  393.     wait(timeout);
  394.     }
  395.  
  396.     /**
  397.      * Causes current thread to wait until another thread invokes the 
  398.      * {@link java.lang.Object#notify()} method or the 
  399.      * {@link java.lang.Object#notifyAll()} method for this object. 
  400.      * In other word's this method behaves exactly as if it simply 
  401.      * performs the call <tt>wait(0)</tt>.
  402.      * <p>
  403.      * The current thread must own this object's monitor. The thread 
  404.      * releases ownership of this monitor and waits until another thread 
  405.      * notifies threads waiting on this object's monitor to wake up 
  406.      * either through a call to the <code>notify</code> method or the 
  407.      * <code>notifyAll</code> method. The thread then waits until it can 
  408.      * re-obtain ownership of the monitor and resumes execution. 
  409.      * <p>
  410.      * This method should only be called by a thread that is the owner 
  411.      * of this object's monitor. See the <code>notify</code> method for a 
  412.      * description of the ways in which a thread can become the owner of 
  413.      * a monitor. 
  414.      *
  415.      * @exception  IllegalMonitorStateException  if the current thread is not
  416.      *               the owner of the object's monitor.
  417.      * @exception  InterruptedException if another thread has interrupted
  418.      *             the current thread.  The <i>interrupted status</i> of the
  419.      *             current thread is cleared when this exception is thrown.
  420.      * @see        java.lang.Object#notify()
  421.      * @see        java.lang.Object#notifyAll()
  422.      */
  423.     public final void wait() throws InterruptedException {
  424.     wait(0);
  425.     }
  426.  
  427.     /**
  428.      * Called by the garbage collector on an object when garbage collection
  429.      * determines that there are no more references to the object.
  430.      * A subclass overrides the <code>finalize</code> method to dispose of
  431.      * system resources or to perform other cleanup. 
  432.      * <p>
  433.      * The general contract of <tt>finalize</tt> is that it is invoked 
  434.      * if and when the Java<font size="-2"><sup>TM</sup></font> virtual 
  435.      * machine has determined that there is no longer any
  436.      * means by which this object can be accessed by any thread that has
  437.      * not yet died, except as a result of an action taken by the
  438.      * finalization of some other object or class which is ready to be
  439.      * finalized. The <tt>finalize</tt> method may take any action, including
  440.      * making this object available again to other threads; the usual purpose
  441.      * of <tt>finalize</tt>, however, is to perform cleanup actions before 
  442.      * the object is irrevocably discarded. For example, the finalize method 
  443.      * for an object that represents an input/output connection might perform
  444.      * explicit I/O transactions to break the connection before the object is
  445.      * permanently discarded. 
  446.      * <p>
  447.      * The <tt>finalize</tt> method of class <tt>Object</tt> performs no 
  448.      * special action; it simply returns normally. Subclasses of 
  449.      * <tt>Object</tt> may override this definition.
  450.      * <p>
  451.      * The Java programming language does not guarantee which thread will 
  452.      * invoke the <tt>finalize</tt> method for any given object. It is 
  453.      * guaranteed, however, that the thread that invokes finalize will not 
  454.      * be holding any user-visible synchronization locks when finalize is 
  455.      * invoked. If an uncaught exception is thrown by the finalize method, 
  456.      * the exception is ignored and finalization of that object terminates.
  457.      * <p>
  458.      * After the <tt>finalize</tt> method has been invoked for an object, no 
  459.      * further action is taken until the Java virtual machine has again 
  460.      * determined that there is no longer any means by which this object can 
  461.      * be accessed by any thread that has not yet died, including possible
  462.      * actions by other objects or classes which are ready to be finalized, 
  463.      * at which point the object may be discarded.
  464.      * <p>
  465.      * The <tt>finalize</tt> method is never invoked more than once by a Java
  466.      * virtual machine for any given object.
  467.      * <p>
  468.      * Any exception thrown by the <code>finalize</code> method causes 
  469.      * the finalization of this object to be halted, but is otherwise 
  470.      * ignored. 
  471.      */
  472.     protected void finalize() throws Throwable { }
  473. }
  474.